#+TITLE: EmacsGME Readme

* EmacsGME - Emacs GameMaster Emulator

EmacsGME v0.2

### SOMEONE ELSE WANTED TO END PULL REQUESTS, SO THIS PROJECT HAS MOVED BACK TO GITHUB TO SIMPLIFY THINGS
https://github.com/CategoryQ/EmacsGME

Future updates will be over there


* Introduction

EmacsGME is a GameMaster emulator in the style of MythicGME/CRGE/etc, implemented in emacs-lisp for playing solo-roleplaying games entirely within org-mode (or plain text) documents.

As this is my first real use of emacs-lisp, a lot of it is just me trying out different things in a literate-programming style, with an explanatory document (that is overly commented) that tangles into an emacs-lisp file for easy addition into any emacs-setup.


* Installation

This will have to be manually added for the time being, this is far from being ready for MELPA - if it ever will be.
For now, the simplest way to add this to your install is to clone this repo, and place the following into you emacs config:-
#+BEGIN_SRC org
(load-file "/path/to/egme.el")
#+END_SRC
Be sure to put in the correct path for where your copy of ~egme.el~ is saved.

If you are doing any hacking on the main org file, another option is:-
#+BEGIN_SRC org
(org-babel-load-file "/path/to/egme.org")
#+END_SRC
to have it automatically tangled and loaded on startup.


* Usage

Usage should be easy to gleam by reading the ~egme.org~ - I have tried to heavily document each function as I write them, not just in how it works but how I hope to extend in the future.

** Output to User

All output is printed into the current buffer, within an org-mode style "GameMaster" block, so that the results can be folded away. On the TODO list is to add proper export styles, so your actual plays can be easily and prettily shown as HTML/PDF/whatever...

org-files are the preferred place to play - headings can help define scenes, game info can be hidden in drawers, and more. If not using org-mode, then org-mode will be enabled in the game buffer whenever output is written.

** Dice Roller

The first main feature is the dice roller, the function "egme-roll-dice". This can either be called with "M-x egme-roll-dice", or by the default keybind of "C-c C-g r". 
After calling, the user is asked to input a dice roll into the mini-buffer. This is to be input as per any usual RPG dice roll, with a modifier, without spaces. Examples of valid choices are:-
- 1d20
- 2D6+3
- d666
- 3d10-5
This will accept any numbers for the dice type, and will roll dice with that range of numbers. This is only treated differently when using multiple-6 dice (D66,D666,D6666...) - in those cases, it will roll that many 6-sided dice and combine them for each digit of the result.
Hit return, and the results will be printed into the current buffer like these examples:-

#+BEGIN_SRC org
#​+BEGIN_GameMaster
Rolled:  2d12+8
Result:  20
#​+END_GameMaster
#+END_SRC

#+BEGIN_SRC org
#​+BEGIN_GameMaster
Rolled:  1d666
Result:  646
#​+END_GameMaster
#+END_SRC

This function keeps a history of rolls that have been made previously - if you give it no input, then it will reroll the last dice type, or you can scroll back and forth with the up/down keys.

** Yes/No Oracle

This features is the main driver of solo-roleplaying with EmacsGME, the yes/no oracle. This function is named "egme-y-n-oracle", and can be called interactively with "M-x egme-y-n-oracle", or with the default keybind of "C-c C-g q".
Once called, it will ask the user what question is being asked. Here you can type a question into the minibuffer, which will be included with any output - this is optional. It will also scan the current line, and if a question is found it will be used as the initial input.
Once a question has been set (or given blank input) then the function asks for probability. This is a sliding scale between +4 and -4, with a description ranging from "Near Certain" to "Near Impossible" - this will affect the likelihood of getting a yes or no, for tweaking probabilities on a per-question case.. Options are chosen by typing the modifier, or scrolling between them using left & right on the keyboard. The default option is "0  Even Odds" - just hit enter for a question with unclear probability. An example of this output is:-

#+BEGIN_SRC org
#​+BEGIN_GameMaster
   Question:  Is the door locked?
Probability:  Likely
------------
     Answer:  Yes
#​+END_GameMaster
#+END_SRC

In some cases, these yes/no answers are extended with answer modifiers or random events...

*** Answer Modifiers

The answers are further modified - in some cases there will be an extremely response, or a partial response. All the possible responses are:-

- Yes, and...
- Yes
- Yes, but...
- No, but...
- No
- No, and...

An example of that output is:-

#+BEGIN_SRC org
#​+BEGIN_GameMaster
   Question:  Does the guard notice me?
Probability:  Even odds
------------
     Answer:  Yes, and...
#​+END_GameMaster
#+END_SRC

An "and..." implies the answer goes beyond the basic. So "Yes, and.." is exceptionally positive, and "No, and..." is exceptionally negative.
Getting "but..." implies a partial success/failure. So "Yes, but..." is partially positive, and "No, but..." is only partially negative.

*** Random Events

As time goes by, there is an ever-increasing chance of a random event occurring each time you ask a question. When a random event occurs, it is added to the output of the oracle.
A random event consists of the focus (what/who is affected by the event), and the detail (a random Action & Subject word combined). Example of a random event occurring is:-

#+BEGIN_SRC org
#​+BEGIN_GameMaster
   Question:  Is the machine switched on?
Probability:  Very Unlikely
------------
     Answer:  No
------------
Random Event!
      Focus:  PC Negative
     Detail:  Divide / Jealousy
#​+END_GameMaster
#+END_SRC

The likelihood of an event happening can be set by the user, through the variable ~egme-random-event-threshold~, which can is available through the ~customize~ system.

The player is left to interpret what these results mean in the context of their game.

The Focus table is based on the random events from [[http://wordmillgames.com/mythic-game-master-emulator.html][Mythic GME]], by Word Mill games. The default Action & Subject lists come from my physical card deck, [[https://quintendo.uk/category/solo-sci-fi-sidekick/][Solo Sci-Fi Sidekick]].

** NPC & Thread lists

Details of current major NPCs and story threads are also managed within each game file. The data is stored within org drawers at the end of each file, named ~:NPCS:~ and ~:THREADS:~ - these remain folded to avoid cluttering up what you see. Even in standard text files, if org-mode is on your system the text in these drawers will be made invisible to you during normal play.

Each list has a function to add a new entry to the list, with a default keybind:-

- C-c C-g n - ~egme-add-npc~
- C-C C-g t - ~egme-add-thread~

And there are counterparts to delete from the lists - the same bind but with a final capital letter:-

- C-c C-g N - ~egme-delete-npc~
- C-c C-g T - ~egme-delete-thread~

When adding to a list, input is taken from the minibuffer. When deleting, you chose an option in the minibuffer through ~ido-completing-read~.

These tie into the random event system - if a random event concerns a thread, it will select one at random for the event. Or if a random event concerns an NPC, a random one will be shown (with the exception of the "New NPC" event). For example:-

#+BEGIN_SRC org
#​+BEGIN_GameMaster
   Question:  Do they spot me approaching?
Probability:  Unlikely
------------
     Answer:  No
------------
Random Event!
      Focus:  NPC positive
        NPC:  Henrethia
     Detail:  Procrastinate / Death
#​+END_GameMaster
#+END_SRC
#+BEGIN_SRC org
#​+BEGIN_GameMaster
   Question:  Is it heavily guarded?
Probability:  Likely
------------
     Answer:  Yes
------------
Random Event!
      Focus:  Move towards thread
     Thread:  Escape the encampment
     Detail:  Move / Randomness
#​+END_GameMaster
#+END_SRC

Interpretation of the detail is still up to the player, but can push the game in new and exciting ways.

** Dashboard

With the default keybinds, ~C-C C-g d~ opens the dashboard buffer. This extra split buffer sits on the right of the game file by default, and shows the current contents of the NPC & thread lists. It will automatically refresh when NPCs/threads are added or deleted, so it can be a handy resource.

This will show more info in the future - current ideas include the current eGME keybinds, last roll results, and more...

** More Details

The entire system is developed from a pen & paper system based on actual dice rolls, details of this system can be found within the ~egme.org~ file against each function.


* Changelog

- v0.2 - Added list handling and dashboard for basic game-state display
- v0.1 - Initial release


* TODO List

The following items are currently on the TODO list - I am open to further suggestions of how this can be improved.

- Show keybinds in dashboard
- [DONE] +Rework dashboard function, so that it toggles the info buffer+ Added a toggle function and bound that key
- More game-state info in the dashboard? +Dice rolls DONE+
- [DONE] +Add user customization for random event occurrences+
- Add random events for new NPC/thread, which also prompts user to update the list
- Add a random image oracle for extra inspiration (from a user-specified directory)
- Convert to a true minor mode, dependent on org
- Function to "initialise" a game file - set title/description/lists/properties - and styling info for the GameMaster block for exporting
- Update this README to better reflect the reality of usage (the Sisyphean task)

  
* Licensing

EmacsGME is licensed under the GPLv2, see included LICENSE file for details.
